Window Library Enhancements - Toolbar Support 11.1 Introduction This section describes the additional features of the Window Library. All enhancements are backwards compatible with previous versions of the AES, so existing applications will continue to work. The new feature will work on all machines with an AES version greater than 4.1. The enhancements to the Window Library are: o Toolbar support has been added to the AES. o wind_set() may be used to attach, change or remove a Toolbar from a window. o wind_get() may be used to see which Toolbar, if any, is attached to a window. In addition, wind_get() may be used to get the the Toolbar rectangle list for custom redraws. o Mouse clicks on objects within the Toolbar generate Message Events. o GEM AES will handle the Toolbar when a window needs to be moved, sized or redrawn. 11.2.1 Toolbar Introduction A Toolbar is an OBJECT tree that is located below the INFO line of a window but above the work area. Toolbars are a convenient way for applications to display button and status information. 11.2.2 Division of Labor GEM AES and the application divide responsibility for proper TOOLBAR management. GEM AES's responsibilities include the following: o Updating the x and y position of the Toolbar when the window is moved, sized and/or fulled. o Ensuring that the window is configured to the size required for the window parts and Toolbar. o Setting the width of the Toolbar ( ROOT ) to be the width of the window. o Redrawing the Toolbar when a WM_REDRAW message is received. o Sending a Message Event to the application whenever the user clicks on a TOUCHEXIT object within the Toolbar. The state of the SHIFT, ALT and CTRL keys and the number of button clicks that occurred are also sent. The application is responsible for the following: o Building an object tree with any buttons designated as TOUCHEXITs. o If the Toolbar contains any child objects that are meant to be the width of the window, the application is responsible for changing the ob_width of that object. The width would normally have to be changed whenever the application receives a FULLER and/or a SIZER message. o Handling user-defined objects within the Toolbar. o Redrawing any objects that changes their visual appearance. The application must take care that the redraw is properly clipped to the window. This is done by walking the rectangle list of the Toolbar and redrawing accordingly. o Screen resolution differences are up to the application to resolve. For example, the height of an icon in ST Medium is different than in TT Medium. o The colors used by the Toolbar are the responsibility of the application. 11.2.3 Window Management Calls An application will use the calls below to manage the Toolbar. o To attach a Toolbar to a window, the application should call wind_set( wid, WF_TOOLBAR, ... ); with the address of the Toolbar. If the call is made while the window is open, the window will adjust itself to take into account the height of the Toolbar. o To change the Toolbar from one Toolbar to another, the application should call wind_set( wid, WF_TOOLBAR, ... ); with the address of the new Toolbar. If the call is made while the window is open, the window will adjust itself to take into account the height of the new Toolbar. o To remove the Toolbar from the window, the application need only call wind_set( wid, WF_TOOLBAR, ... ); with NULL parameters. If the call is made while the window is open, the window will adjust itself to take into account the lack of a Toolbar. o Closing a window with wind_close() does not remove the Toolbar from the window In this way, the application may reopen the window with the Toolbar still present. o Deleting a window with wind_delete() will remove any attached Toolbar. o To receive mouse clicks on Toolbar objects, all button objects should be set to TOUCHEXIT. When the user clicks on a TOUCHEXIT, GEM AES generates a Message Event. The message WM_TOOLBAR has a maximum length of 16 bytes and is defined as: o word 0 - WM_TOOLBAR o word 1 - ap_id of the application that sent the message. o word 2 - 0 o word 3 - the handle of the window o word 4 - the object click on o word 5 - the number of clicks o word 6 - the state of the SHIFT, ALT and CTRL keys o word 7 - 0 11.2.4 Support of Overlapping Windows GEM AES can handle the redraws for the Toolbar when windows overlap. However, a window with a Toolbar will not generate any Message Events unless it is the TOP window. 11.2.5 Redrawing and Updating To redraw the Toolbar, the application should walk the rectangle list. The current way to get the rectangle list is to call wind_get() with WF_FIRSTXYWH and WF_NEXTXYWH. However, these parameters will only return the rectangles for the work area of the window. Therefore, in order to get the rectangle list for the Toolbar area, the application should call wind_get() with WF_FTOOLBAR and WF_NTOOLBAR, which will return the first Toolbar rectangle and the next Toolbar rectangle respectively. The application will need to redraw the Toolbar for the following: o If the Toolbar contains a user-defined object, the redraw must be done by the support code for that object. Since the window will not necessarily be the top window, redrawing via the rectangle list is crucial. o If the application changes the state of an object within the Toolbar, the object will need to be redrawn. For example, the application changes the ob_state of a button to SELECTED. The dirty area will consist of the object's rectangle plus the effects of any 3D, Shadowing, outline etc.. Again, since the window will not necessarily be the top window, redrawing via the rectangle list is crucial. The application may have to update the Toolbar for the following: o If the Toolbar contains an object that is meant to be the width of the window AND is not the ROOT object, the application will need to set the width of the object in response to several Message Events. These messages include FULLER and SIZER events. Simply set the width of the object before calling wind_set( wid, WF_CURRXYWH, ... ); to set the new current size of the window. o If the window is iconified, the application need not handle the Toolbar until the window is no longer iconified. o If the window is sized and/or fulled such that the width of the window is smaller than the Toolbar, the Toolbar will merely be clipped. Buttons that are clipped are obviously not accessible. In these situations, the application may elect to change the height of the Toolbar and reposition the buttons at its discretion. When the applications calls wind_set( wid, WF_CURRXYWH, ... ) to set the new current size of the window, GEM AES will rebuild the window based upon the new height of the Toolbar. o If the application wishes to merely switch one Toolbar with another, the application should call wind_set( wid, WF_TOOLBAR, ... ) with the new OBJECT tree. o In the same instance, if the application wishes to remove the Toolbar, the application should call wind_set( wid, WF_TOOLBAR, ... ) with NULL parameters. 11.3 Window Library Routines - Toolbar Support Addendum The Toolbar code affect the following routines. For more information about these and other routines, please see the GEM AES documentation. 11.3.5 WIND_GET() - Gets information on a particular window #include result=wind_get( handle, field, x,y,w,h ); WORD result error result WORD handle; window handle WORD field; information wanted WORD *x; value depends upon information requested WORD *y; value depends upon information requested WORD *w; value depends upon information requested WORD *h; value depends upon information requested The Toolbar field values are: WF_TOOLBAR - 30 - x and y give the address of the Toolbar object tree. - x is the high word of the address - y is the low word of the address WF_FTOOLBAR - 31 - the coordinates of the first rectangle in the Toolbar's rectangle list. - x ( X - coordinate ) - y ( Y - coordinate ) - w ( width ) - h ( height ) WF_NTOOLBAR - 32 - the coordinates of the next rectangle in the Toolbar's rectangle list. - x ( X - coordinate ) - y ( Y - coordinate ) - w ( width ) - h ( height ) 11.3.6 WIND_SET() - Sets new values for the fields that determine how a window is displayed. #include result=wind_set( handle, field, x,y,w,h ); WORD result error result WORD handle; window handle WORD field; information to set WORD x; value depends upon field WORD y; value depends upon field WORD w; value depends upon field WORD h; value depends upon field The Toolbar field values are: WF_TOOLBAR - 30 - Used to attach, change or remove a Toolbar. To remove a Toolbar, set (x,y) to NULL. - x is the high word of the address - y is the low word of the address 11.3.9 WIND_CALC() - Calculates the X- and Y-coordinates and the width and height of a window's work area or border area. This routine calculates the X and Y coordinates and the width and height of a window's work area or border area. wind_calc() does this by adding up the widths and heights of the window parts passed in via 'kind'. Since no window handle is involved, wind_calc() cannot calculate the work area or border area of a window that has an attached Toolbar. However, it is possible to adjust the values returned since the application knows about the height of the Toolbar. The height of the Toolbar should include the area occupied by any 3D effects, shadowing, border thickness etc.. To compensate for the Toolbar, simply increase the height of the border area by the height of the Toolbar. In addition, since the work area is below the Toolbar, increase the y - coordinate of the work area by the same amount. The height of the work area remains the same. 11.4 DEFINES Please be sure to include these defines in your AES.H include file for your compiler. #define WF_TOOLBAR 30 Toolbar parameter for wind_get/set #define WF_FTOOLBAR 31 Get the First Toolbar rectangle #define WF_NTOOLBAR 32 Get the Next Toolbar rectangle #define WM_TOOLBAR 37 Toolbar Button Event Message Event Library Enhancements - Toolbar Support 4.2.5.1 Predefined GEM AES Messages The Toolbar adds a new Message Event to the existing list of AES Messages. For additional information on the Event Library, please see the AES Documentation. GEM AES provides several predefined message types. Each type has a maximum length of 16 bytes. All the predefined message types define the first three words in the same way: o WORD 0 - A number identifying the message type. o WORD 1 - The ap_id of the application that sent the message. o WORD 2 - The length of the message, not counting the predefined 16 bytes. 4.2.5.14 WM_TOOLBAR GEM AES uses this message to tell the application which Toolbar object the mouse clicked on. The object must be a TOUCHEXIT and not disabled. In addition, the window must be the TOP window. o WORD 0 37 o WORD 3 the handle of the application's window o WORD 4 the Toolbar object clicked on o WORD 5 the number of mouse button clicks o WORD 6 the state of the SHIFT, ALT and CTRL keys